/*
 * Copyright (C) 2012-2013  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.swing;

import java.awt.Container;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.util.Map;

/**
 * ISwingGenerator : The Swing generator interface.
 * 
 * <p>
 * A service implementing this interface provides a way to externalize Swing
 * GUI. The description format is implementation-specific and is declared in the
 * {@link #DESCRIPTION_FORMAT} service property.
 * </p>
 * 
 * <p>
 * This interface main purpose is to ease the generation of Swing interfaces
 * from external resources, mainly textual files (plain, XML, ...).
 * </p>
 * 
 * @author Romain DUBOIS
 */
public interface ISwingGenerator {

    /** The supported input format property name */
    String DESCRIPTION_FORMAT = "nemos.swing.format"; //$NON-NLS-1$

    /**
     * Parse {@code pInput} and return a new instance of the described
     * component.
     * 
     * @param pInput
     *            The stream to parse
     * @return The described component
     * @throws IOException
     *             If a reading error occurred
     * @throws GenerationException
     *             If the input is not valid
     */
    Container getComponent(InputStream pInput) throws IOException, GenerationException;

    /**
     * Parse {@code pInput} and return a map of the described components with
     * their IDs.
     * 
     * @param pInput
     *            The stream to parse
     * @return The described components
     * @throws IOException
     *             If a reading error occurred
     * @throws GenerationException
     *             If the input is not valid
     */
    Map<String, Object> getComponents(InputStream pInput) throws IOException, GenerationException;

    /**
     * Parse {@code pFile} and return a new instance of the described component.
     * 
     * @param pFile
     *            The file to read
     * @return The described component
     * @throws IOException
     *             If a reading error occurred
     * @throws GenerationException
     *             If the input is not valid
     */
    Container getComponent(File pFile) throws IOException, GenerationException;

    /**
     * Parse {@code pFile} and return a map of the described components with
     * their IDs.
     * 
     * @param pFile
     *            The file to read
     * @return The described components
     * @throws IOException
     *             If a reading error occurred
     * @throws GenerationException
     *             If the input is not valid
     */
    Map<String, Object> getComponents(File pFile) throws IOException, GenerationException;
}
